ShareWare OnLine 2/ShareWare OnLine Volume 2 (CMS Software)(1993).iso/comm2/ppage210.zip/PPAGE.DOC

Text File | 1993-01-09 | 21KB | 579 lines

                          Pocket Pager Version 2.10
                           Written by David Shafer

                           Released January 9, 1993

                 Copyright (c) 1993, The PEFH Software Group
                             All rights reserved.

                 Created with Searchlight Programmer's Library
               Portions Copyright (c) 1992 Searchlight Software



                               "What is that?"
                                "What's what?"
                          "YOU have a Pocket Pager!"

                      - Star Trek IV : The Voyage Home

































                               1





     Table of Contents
     -----------------
     1.  Introduction ............... 2
     2.  Legal Stuff ................ 3
     3.  Disclaimer ................. 3
     4.  Distribution ............... 3
     5.  Installation ............... 4
     6.  Configuration Program ...... 4
         6.1.  System Information ... 4
         6.2.  Miscellaneous ........ 5
         6.3.  Chat Colors Setup .... 5
         6.4.  String Definitions ... 5
         6.5.  Security Levels ...... 5
         6.6.  Time Restrictions .... 6
     7.  External Page Bells ........ 6
         7.1.  PPCmf ................ 7
         7.2.  PPVoc ................ 7
     8.  Operation .................. 8
     9.  Registration ............... 9



1.  Introduction

     Thank you for checking out Pocket Pager!  If you're like me, you love
Searchlight BBS.  The menus are fantastic, the internal communications
support makes programming a breeze, and it generally has the look and feel of
an extremely professional piece of coding.  One problem...  As terrific as
everything else about Searchlight is, the Sysop paging system is seriously
lacking in features.

       Not a problem!  Pocket Pager combines the best features of some of
today's best BBS software with the ideas of Sysops around the world who give
me their input.  The result is a program that's both up-to-date and complex,
yet as easy to configure as Searchlight BBS.

      These are all of the features offered by Pocket Pager 2.00:

   ∙ Control Sysop availability with Scroll Lock
   ∙ Asks for a reason for page
   ∙ Updates "C" flag on SL's status line
   ∙ Complete log file detailing
        - Day of week, date, and time of page
        - User's reason for page
        - How Sysop responded
   ∙ Configurable length of time for page
   ∙ Configurable text strings
   ∙ Configurable security levels with independent "Ask Reason Prompt?",
      "Override Time of Day?", and "Override Scroll Lock?" settings for each
   ∙ External DOS paging commands for Sound Blaster or other utilities,
      independently configurable by security level
   ∙ Beginning and Ending paging time 'windows', independently
      configurable by day of the week
   ∙ Split-Screen/ASCII Line Chat
   ∙ Drop User to DOS and Sysop Jump to DOS functions in both chat modes
   ∙ Traps errorlevels from external pages, allowing programmers to write
      custom alarm functions


                               2





   ∙ '/C' command-line parameter bypasses page, and jumps directly into
      Split-Screen or ASCII Line Chat

      These features are new to Pocket Pager 2.10:

   ∙ Optionally block multiple pages during one logon
   ∙ *TRUE* SoundBlaster support in the form of .CMF and .VOC files
   ∙ Bugs related to DOS shells and line-wrap eliminated
   ∙ Screen redraw now keeps track of any existing chat text
   ∙ Drop to DOS and Jump to DOS also remember any existing chat text
   ∙ 5 lines retained when a window is scrolled, instead of only 3
   ∙ Input, status bar, and PPConfig colors taken from Config.SL2
   ∙ ANSI split-screen and ANSI/ASCII line chat colors defined in PPConfig
   ∙ Status line expanded to include SL's flags


     For more information on The PEFH Software Group, the group responsible
for this program, refer to PEFH.DOC, included in this archive.



2.  Legal Stuff

     This program was created by David Shafer of The PEFH Software Group.
You may run this program, distribute it freely, make copies, etc.  You may
NOT sell this program for a profit.  A distribution fee may be charged, as
long as it only covers the price of the disk and/or postage.  You also may
not alter the program or any included files, and you may not alter the
archive.



3.  Disclaimer

     Hopefully this program is bug-free and it was not intended to be
harmful, but under no circumstances will The PEFH or David Shafer take
responsibility for any harm that comes out of using this program.  You're
using it of your own free will, and we can't make any guarantees.  If Pocket
Pager begins to smoke, cover head and seek shelter immediately.



4.  Distribution

     The following files should be included in this archive:

         PEFH.DOC      -  PEFH Information File
         200TO210.EXE  -  Update Configuration File
         PPAGE.EXE     -  Main Executable
         PPAGE.DOC     -  Documentation (This File)
         PPAGE.HIS     -  Revision History
         PPAGE.REG     -  Registration/Comment Form
         PPCONFIG.EXE  -  Configuration Program

         PPCMF.EXE     -  SoundBlaster .CMF Player
         PPVOC.EXE     -  SoundBlaster .VOC Player


                               3






         SIREN.EXE     -  Sample External Bell
         SIREN.PAS     -  Sample External Bell (Pascal Source)

     If not all of the files have been included, contact a Support or
Distribution BBS (listed in PEFH.DOC) for an official distribution archive,
and delete the incomplete archive.



5.  Installation

     To install Pocket Pager 2.10 for the first time, begin by copying all of
the files to one directory, such as 'C:\DOORS\PPAGE'.  Make sure you have all
of the files listed in the "Distribution" section.

     For users to be able to run Pocket Pager, you'll have to set it up as a
menu entry, or as an external door in SLBBS 2.15.  'Communications Support'
should be set to Standard, 'Abort Method' to Terminate, 'Write Protection' to
No, 'Parameter File' to None, and 'Pause After Door' to No.  If you're
running SLBBS 2.15, set up these same option in your DOORS.DEF file.  Simply
run the PPage.Exe file out of the Pocket Pager directory you created.  If
you're in monochrome mode, be sure to 'Force Color', so your users will see
the color correctly.

     Pocket Pager itself does not need to be run with any parameters in
version 2.00 and beyond.  For this reason, Pocket Pager needs to know where
your Config.SL2 file it located.  Set the 'SLBBS' environment variable to the
apropriate path, unless Config.SL2 is located in the current directory when
Pocket Pager is run.  This is accomplished with the DOS 'SET' command, as in
'SET SLBBS=C:\SLBBS' or 'SET SLBBS=C:\BBS'.



6. Configuration Program

     Once Pocket Pager is installed, you will want to configure your copy.
Change to the Pocket Pager directory you created, and run PPConfig.Exe.
Since direct screen writes are not used, PPConfig CAN be used remotely.
Below, each of the main configuration categories is explained.

6.1. System Information

     The fields in the System Information category deal mainly with registra-
tion information.  'Sysop Name' should be set to your name as you want it to
apear to your users.  In MOST cases, this will be your full, real name.  'BBS
Name' is, of course, the name of your Bulletin Board System as you want it to
apear in Pocket Pager.  Registration Key should be set to "0" if you haven't
registered.  None of these setting should be changed after you register, as
it will nullify your registration!








                               4





6.2. Miscellaneous

     The miscellaneous category will grow as Pocket Pager develops.  It
currently holds three fields.  The first field is for specifying a log file
that Pocket Pager will maintain.  By looking at this file, the Sysop can
determine who paged while (s)he was away, and perhaps leave E-Mail to those
users if it sounds important.  A full path AND filename should be specified.
If this field is left blank, no log file will be created.  The "Alarm Length"
can also be configured from this menu.  A value from 0 to 255 seconds may be
entered.  The bottom option, "Allow Multiple Pages", decides whether or not
users can page more than once on a call.  This is a good way to eliminate
twits who page 20 times in a row saying only "Stuff" as their Reason for
Page.


6.3. Chat Colors Setup

     Pocket Pager grabs as many color settings as it can from Searchlight
BBS.  This includes all of the colors used for PPConfig, as well as input
bars and status lines.  The remaining colors (aside from those in the main
screen, which are hard-coded), are the colors used in the ANSI split-screen
and ANSI/ASCII line chatting modes.  These can all be selected from the Chat
Colors Setup menu in PPConfig.  Most of the fields are self-explanatory, as
are the available color selections.  If you aren't sure of what color
settings to use, it never hurts to experiment!


6.4. String Definitions

     From this menu, the major information text strings used by Pocket Pager
can be configured for your BBS.  In this way, you can make Pocket Pager fit
into the mood, theme, or style of your Bulletin Board.  The purpose of each
string should be self-explanatory.  (Adding your name to the strings is a
great way to personalize your copy of Pocket Pager!  Instead of saying "The
Sysop isn't in right now.", have your BBS respond with something like "Bob is
currently seeking the Ultimate Answer.  Try again in about 42 minutes.")


6.5. Security Levels

     This section represents what is probably one of Pocket Pager's most
powerful features.  Up to twelve security definitions can be created, with
independent settings for each.  A configurable default definition covers any
security levels not already defined by the Sysop.

     Within each definition, several options can be defined.  The Access Name
will be displayed both in the log file, and on the status line at run time.
Names like "Visiting Sysop" or "Twit" can help the Sysop identify the person
paging, if they are not familiar.  The 'BBS Access Level' tells Pocket Pager
who fits into this defintion, according to their BBS Access Level.  The next
three parameters have no effect unless Pocket Pager detects a valid
registration key: the 'Reason for Page?' prompt, and the time-of-day and
Scroll Lock paging restrictions all have override options, configurable by
security level.  These options should be used carefully, as you could end up
having people page you at all hours of the night!



                               5





     The final field is for executing an external page bell, rather than
using Pocket Pager's internal telephone bell.  You may enter .COM or .EXE
files, or even .BAT files and DOS commands.  If Pocket Pager doesn't see the
 .COM or .EXE extension, it will run your programm in a Command.Com shell.
To execute Command.Com, it will first look for the COMSPEC environment
variable.  If COMPSEC isn't found, Command.Com will be run from the current
directory.  (An example external page bell, Siren.Exe, has been included in
this archive.)


6.6. Time Restrictions

     This section is also one of Pocket Pager's strong points.  For each day
of the week, a paging "window" can be defined using starting and ending
paging times.  In this way, you can make sure nobody is paging you too early,
or too late.  An override options is available by security level on
registered systems.



7. External Page Bells

     In addition to programs like VPlay, programmers can write their own
simple page bells for use in Pocket Pager.  The easiest language to use for
this purpose is Turbo Pascal, though any language will work.  For starters,
placing "DirectVideo := False" in your Turbo Pascal programs will echo
everything (including colors!) to the remote user.  For more detailed
information, check out "SOME DOOR PROGRAMMING TIPS" in the Searchlight
Owner's Manual, or look at the Searchlight TPU.  Both are excellent resources
for SLBBS programmers.

     As of version 2.00, Pocket Pager will look for errorlevel returns from
external page programs.  If you are programming an external bell program, you
may wish to return the following DOS errorlevels under the appropriate
conditions:

          0  :  No Answer (timeout)
          1  :  User Aborted (keypress from remote)
          2  :  Sysop Aborted (keypress from local)
          3  :  Sysop Answered (Alt-C)
          4  :  Force ASCII Chat (Shift-Alt-C)

     In Turbo Pascal, these codes can be returned using "Halt(b);" as the
exit point of your program, where 'b' is a byte value corresponding to the
definitions above.  Pocket Pager will detect the errorlevel, and take the
appropriate action, like displaying a text string or entering chat mode.

     For an example of programming external page programs, look at Siren.Pas,
included in this archive.  It shows how programs interface with Pocket Pager,
and some of the basic techniques to use.  (Note:  Compiling it requires
SLTPU, from Searchlight Software.  This should be available for download on
most Searchlight Support Systems.)

     As of version 2.10, Pocket Pager includes two utilties for SoundBlaster
owners that interface with Pocket Pager's external page bell system.  They
are each explained in greater detail below:


                               6






7.1. PPCmf.Exe

     Many great songs are available for the SoundBlaster in .CMF format.  You
can find just about anything, from movie and T.V. themes, to pop and
classical instrumentals, to holiday music.  With PPCmf, you can play these
songs through your SoundBlaster when a user pages.  Pocket Pager's security
defintions allow you to specify different songs for different security
levels, so you can tell who's paging just by the music that's playing!

     To use PPCmf, just make sure SBFMDrv.Com is loaded first.  Usually, this
will be in your Autoexec.Bat, or some other .BAT file that executes only once
each time the computer boots up.  Then enter the program into one of Pocket
Pager's security definitions (be sure to include the .Exe extension so that a
Command.Com shell isn't executed), followed by the song you want to be
played.  The song will be stopped when the paging time defined in PPConfig
expires.  An example would be:

     PPCmf.Exe Crystal.Cmf

     I've included some example songs that I use, so that you'll have
something to start with.  I doubt you'll have trouble coming up with music,
though.  Huge libraries of .CMF files exist on BBSes around the world!  PPCmf
can also be used from DOS to listen to them before installing them on your
system.

     Pocket Pager's standard keys (Alt-C to chat, Shift-Alt-C to force ASCII,
any other keys locally to abort, any keys remotely to abort), are monitored
by PPCmf and appropriate errorlevels are returned, so that Pocket Pager will
enter chat or exit back to Searchlight accordingly, and make the appropriate
log file entries.


7.2. PPVoc.Exe

     Another great feature of the SoundBlaster is its ability to play back
digitized sound files.  I wasn't about to let this go to waste!  As with .CMF
files, there is abundance of .VOC files of every kind, and any of them can be
played in Pocket Pager, as long as your system can hold them in memory.  Just
like the .CMF files, you can define different .VOC files for each security
level through PPConfig's security definitions.

     When you run PPVoc.Exe, no driver needs to be resident, but CT-Voice.Drv
needs to be in the current directory.  PPVoc loads this into memory on its
own, and then frees up the memory afterwards.

     The syntax for PPVoc is the same as PPCmf.  Enter the program name into
PPConfig (with the .Exe extension), followed by the .Voc file you want to
play.  PPVoc will stop the .VOC file when the paging time expires, or will
repeat the .VOC file in a loop until the paging time expires.  PPVoc will
respond to keypressed in the same way that PPCmf does.  An example
command-line might be:

     PPVoc.Exe Cow.Voc




                               7






8. Operation

     Once Pocket Pager executes, it will display a status line at the bottom
of the local screen.  This will tell the Sysop the name of the person paging,
their BBS Access Level, and the NAME of their access level as defined in
PPConfig.  It also shows the status of Searchlight's internal system flags.
Using this information, the Sysop can decide whether or not they want to talk
to the person online.

     Before anything else happens, the status of Searchlight's 'C' flag is
checked.  If this flag is turned "On" (meaning the user has already paged),
paging will be blocked if you've instructed Pocket Pager to do so.  The user
will be given the 'User Already Paged' string and returned to Searchlight.

     Both the time-of-day and Scroll Lock status will be checked next.  If
the current time is outside the day's paging window, or scroll lock is
activated, the user will not be able to page, and the 'Sysop Not Available'
string will be displayed from the configuration file.  On registered systems,
users may override these settings, if the Sysop has made that option
available.

     If paging is allowed, the user will be prompted by the 'Reason for Page'
prompt to enter a reason for paging.  Pressing [Enter] without any text will
abort the page and return to Searchlight.  If the "Reason for Page Override"
is set to On, this step will be skipped.

     Next, a Sysop instruction line will apear on the local screen, giving
the Sysop the choice of pressing Alt-C to answer, Shift-Alt-C to force ASCII,
activating Scrl Lock to silence the page (and prevent further pages), or
pressing any other key to abort, which exits to Searchlight with the 'Sysop
Aborted Page' string.  (Note: If the user's Scroll Lock Override is set,
pressing scroll lock will have no effect during the page.)  During the page,
the user also has the option of pressing any key to abort.  If no keys are
pressed, the page will timeout, and the 'No Answer' string will be displayed.

     In any case where the user attempted to page, but never ended up
chatting with the Sysop, the 'C' flag will be set to "On" in Searchlight.
This will show up on Searchlight's internal status bar, and may optionally
block further pages if you've instructed Pocket Pager to do so.

     If all else goes well, and the Sysop answered the page, Pocket Pager
will enter Split-Screen or ASCII Line Chat.  In these modes, the Sysop can
press Alt-J to jump to DOS alone, or Alt-D to drop to DOS with the user.  In
Split-Screen chatting, Ctrl-R redraws the entire screen to compensate for
line noise, and Ctrl-W clears your window.  The Esc key exits chat in both
modes.  If the 'C' flag was set to "On" when the Sysop entered chat, it will
be set "Off".

(Note: Running Pocket Pager with the '/C' parameter bypasses the paging
function, and enters chat mode.  Only the local console should be allowed to
execute this, as a remote user won't be able to exit again by pressing Esc.
If your CoSysops have access to DOS, make sure they are aware of this, and
that your Doors.Def or menu definition provides an "Abort" method.)




                               8






9. Registration

     If you find Pocket Pager useful, you can show your appreciation for the
work that went into it by registering or sending some comments.  A
Comment/Registration form has been included in this archive as 'PPage.Reg'.
Please fill it out, and tell us what you think!  All comments and
registrations should be directed to David Shafer, the author.  (Check the
registration form for the correct address.)

     Remember, you're not required to register!  You can use this program as
long as you want without paying a cent.  More than anything, we just want to
hear what you have to say, so that we can improve the program further.  If
you DO register, however, your registration will be valid for ALL future
upgrades, and any special features will be enabled.











































                               9